Installing Hooks on Pre/Post Request, Update, Release Events

Hooks are based on events. For each event, there is a pre-event hook and a post-event hook. Currently, the only events with hooks are license request, update, and release. For example, you can have a hook function BEFORE the License Manager processes a license request or AFTER a request is processed.

You can use the pre hook to decide on the licensing action, such as looking up the external information before granting a request. However, the post hook can be used for providing custom information to the client.

Executables to Rebuild

>The client application

>The License Manager

Rebuilding the Client Application

The following table provides a list of events and corresponding API for implementing hooking in the client application.

Events	Required API
Pre-request	VLSrequestExt VLSrequestExt2
Post-request
Pre-update*	VLSupdateExt VLSupdateExt2 Both pre and post events can be handled with a single update call only. Also, the update handlers are triggered on manual calls to the VLSupdateExt() and VLSupdateExt2() functions respectively. In the case of auto-updates, the events cannot be handled.
Post-update*
Pre-release	VLSreleaseExt
Post-release

* The pre/post update events are available in  licensing libraries v8.5.3 (Windows) and 8.6.0 (UNIX) onward.

Rebuilding the License Manager

Register a Callback Function using the following Function Prototype:

LSERV_STATUS VLSeventAddHook
(
   int   eventName,
   int   (*handlerFuncPtr)(VLShandlerStruct *, char *, char *, int),
   char* identifier
);

NOTE   The identifier value (specified in callback function) should also match the value passed as identifier in VLSserverInfo Struct structure because this structure is used by client API. For more information on client API, see the Rebuilding the Client Application section).

Returns

Returns LSERV_STATUS_SUCCESS on success. Post events are executed only if the API returns success.

Returns non-zero on failure.

Parameter	Description
eventName	An IN parameter. Specifies the type of event: >LS_REQ_PRE - The handler function will be called right before the License Manager processes the license request. >LS_REQ_POST - The handler function will be called right after the License Manager processes the license request. >LS_REL_PRE - The handler function will be called right before the License Manager processes the license release. >LS_REL_POST - The handler function will be called right after the License Manager processes the license release. >LS_UPD_PRE - The handler function will be called right before the License Manager processes the license update. >LS_UPD_POST - The handler function will be called right after the License Manager processes the license update. But, post events are not executed if the API returns failure due to any reason. In that case, the handler functions registered with LS_UPD_POST events are not called.
handlerFuncPtr	An IN parameter. The callback function for the specified event.
identifier	An IN parameter. The client identifier to match and is required for implementing hooks. The same identifier needs to be set in the VLSserverInfo structure and this structure is further used in VLSrequestExt, VLSreleaseExt, VLSrequestExt2, VLSupdateExt, and VLSupdateExt2 API. The event handler is called only if this identifier is matched. Multiple event handlers can be called for a single registered hook event. However, only the handlers with same identifier will be executed.

Function Prototype (of the Callback Function)

int HandlerFunc
(
   VLShandlerStruct* pHandlerStruct, /* IN */
   char*             inBuf /* IN */
   char*             outBuf /* OUT */
   int                outBufSz /* IN */
);

Returns

>Returns LSERV_STATUS_SUCCESS on success.

>Returns LSERV_STATUS_DENY on failure. If LS_LSERV_DENY is returned in the case of pre event only, the update call fails.

Parameter	Description
pHandlerStruct	A pointer to VLShandletStruct containing client information, feature information, various file information and miscellaneous information.
inBuf	The null-terminated string containing the input message.
outBuf	A pointer to buffer that receives the output message.
outBufSz	The size of the buffer pointer by outBuf.

Steps to Perform

1. Create the hook functions. For example, LSReqPreHook, LSReqPostHook, LSRelPreHook, LSRelPostHook, LSUpdPreHook, and LSUpdPostHook.

You can refer to the following samples for Request and Release functions for details:

•reqprhk1.c and reqprhk2.c - Request pre hook

•reqpshk1.c and reqpshk2.c - Request post hook

•relprhk1.c and relprhk2.c - Release pre hook

•relpshk1.c and relpshk2.c - Release post hook

2.Update the SERVER_HOOK_OBJS variable in the custom32.mak file.

3. Register the hook functions in the License Manager using the srhkdemo.c file

4.Follow the build procedure specified in How to Use the custom32.mak File?.

Code Snippets

Create the Hook Functions

int LSReqPreHook
(
   VLShandlerStruct* pHandlerStruct, /* IN */
   char*             inBuf           /* IN */
   char*             outBuf          /* OUT */
   int               outBufSz        /* IN */
)
{
   if ((inBuf == NULL) || (outBuf == NULL) || (outBufSz == 0))
   {
      return LSERV_STATUS_DENY;
   }
   /* TODO: add the pre-request handler code here */
   return LSERV_STATUS_SUCCESS;
}

Register the Hook Functions in the License Manager

extern int LSReqPreHook(VLShandlerStruct* pHandlerStruct, char* inBuf, char* outBuf, int outBufSz);
LSERV_STATUS VLSserverVendorInitialize(void)
{
   VLSeventAddHook(LS_REQ_PRE, LSReqPreHook, "Hook1");
   return LSERV_STATUS_SUCCESS;
}